MacFormat 1995 June

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1995 June / MacFormat 25.iso / Shareware City / Developers / fortran-to-c-translator-11 / Mac F2C 1.1 / Mac F2C Documentation / INSTRUCTIONS (THINK) < prev next >

Wrap

Text File | 1995-01-29 | 17.1 KB | 382 lines | [TEXT/KAHL]

************************************************* ************************************************* INSTRUCTIONS FOR SETTING UP AND USING Mac F2C WITH SYMANTEC THINK C ************************************************* ************************************************* Before you can use the code produced by Mac F2C, you must set up and build all of the required support libraries. There are also special rules that must be followed when using code produced by Mac F2C. The process and rules are slightly different for Symantec's THINK C and for MetroWerk's CodeWarrior. These instructions are for setting up Mac F2C for use with Symantec THINK C. Refer to the documentation file "INSTRUCTIONS (CodeWarrior)" for instructions on how to set things up for use with MetroWerk CodeWarrior. Users upgrading from previous versions of Mac F2C need to re-install ALL libraries and project files, including main.c and f2c.h. Both library source code and the options settings in the various project files have changed. Users with existing projects using Mac F2C code should either: (a) replace those projects with projects based on the new Mac F2C model projects or, (b) replace main.c and f2c.h and adjust any existing project's option settings to match those in the new model projects. All of the THINK project files shipped with Mac F2C are for THINK C version 7 or better. If you are using an earlier version of THINK, please refer to the additional instructions in the folder "For THINK v6 and Earlier Users". The instructions here are broken into four sections: A. Setting up Mac F2C B. Verifying correct operation C. Translating with Mac F2C D. Using C code produced by Mac F2C ***************************************************************************** A. SETTING UP Mac F2C ********************** Step 1: MOVE THINGS TO THE RECOMMENDED LOCATIONS For easiest and smoothest operation, the support libraries should be installed where the THINK C compiler can find them easily. If you are using THINK version 7, the model project also needs to go in particular location. I recommend you install Mac F2C support files as follows: (1) Drag the _entire_ folder "Mac F2C Libraries" to the folder that contains the THINK Project Manager application. (You can delete the CodeWarrior files "libF77.68k.µ", "libI77.68k.µ", "libF77.PPC.µ", and "libI77.PPC.µ" if you don't need them). (2) The folder "For 'Standard Libraries'" (located in the "THINK Specific Stuff" folder) contains four THINK project files: "ANSI F2C", "unix F2C", "IOStreams F2C", and "CPlusLib F2C". Drag these files (NOT the folder itself) to the "Standard Libraries" folder located in the same folder as the THINK Project Manager application. If you only have THINK C or don't plan to use Mac F2C with the C++ compiler, you do not need "IOStreams F2C" or "CPlusLib F2C". (3) The folder "For '(Project Models)'" (located in the "THINK Specific Stuff" folder) contains two model project folders called "Mac F2C C Project" and "Mac F2C C++ Project". If you are using THINK version 7 or better, drag both folders to the "(Project Models)" folder located in the same folder as the THINK Project Manager application (if you only have THINK C or don't plan to use Mac F2C with the C++ compiler, you don't need the "Mac F2C C++ Project" folder). If you do not have THINK version 7 or better, see the documentation provided for THINK version 6 and earlier users. Step 2: BRING ALL THE LIBRARIES UP-TO-DATE If you are using THINK C version 7.0 or better, the libraries are easily brought up to date using the following steps. If you are using an earlier version of THINK C, please refer to the special instructions in "For THINK v6 and Earlier Users". The easy way to bring the F2C libraries up to date is to use the provided AppleScript. In the folder "THINK Specific Stuff" is the AppleScript "Build F2C Libraries". Drag this file to the "(AppleScripts)" folder located in the same folder as the THINK Project Manager application. Start the THINK Project Manager and choose the "Build F2C Libraries" item from the AppleScript menu. Follow the directions of the prompts. All required libraries will be brought up to date. If this fails or for any reason you wish to bring them up to date manually, simply follow this algorithm: FOR the project files: (1) "libI77a" in the "Mac F2C Libraries" folder (2) "libI77b" in the "Mac F2C Libraries" folder (3) "libF77" in the "Mac F2C Libraries" folder (4) "ANSI F2C" in the "Standard Libraries" folder (5) "unix F2C" in the "Standard Libraries" folder (6) "IOStreams F2C" in the "Standard Libraries" folder (only for C++) (7) "CPlusLib F2C" in the "Standard Libraries" folder (only for C++) REPEAT the following steps: (a) Double-click on the project file. (b) In the THINK Project Manager's "Source" menu, select the "Make" command. (c) Uncheck the "Quick Scan" check-box. (d) Click on the "Use Disk" button. (e) Click on the "Make" button. END REPEAT *** WARNING *** The source code for the Mac F2C Libraries (libI77a, libI77b, and libF77) has name conflicts with Apple's Universal Headers (e.g., a file called "fp.h" appears in both but the two are NOT equivalent files. Once you have built the Mac F2C Libraries, you should remove the source code for these libraries (found in the folders "libF77 Sources" and "libI77 Sources") from the THINK Project Folder tree. Otherwise any of your code that #includes one of the files with conflicted names may inadvertently access the wrong file. ***************************************************************************** B. VERIFYING CORRECT OPERATION OF Mac F2C ****************************************** The folder "Test Project ƒ" contains the following files: (1) "test.f" -- a sample FORTRAN program. (2) "main.c" -- the main program required to run programs produced by with Mac F2C. (3) "f2c.h" -- an include file required to compile programs produced by Mac F2C. (4) "test.c (C Output)" -- what you should get when you translate the sample FORTRAN code files. (5) "Test.π" -- a THINK C v7.0.4 project to run the sample C program. (6) "test.c (C++ Output)" -- what you should get when you translate the sample FORTRAN code files and select the C++ output option. (7) "Test++.π" -- a THINK (Symantec) C++ v7.0.4 project to run the sample C++ program. (8) "Test.68k.µ" and "Test.PPC.µ" -- CodeWarrior project files (not used) Translate the sample FORTRAN program "Test.f" simply by dragging it onto Mac F2C. Do not change any of the options (use "Factory Defaults"). Once you have done this you can compare it with "Test.c (C Output)" to verify that you got the same thing. If so, double click on the THINK project "Test.π" and follow the same steps outlined in the "Bringing Libraries Up-To-Date" section to bring the test project up-to-date. Run it to verify correct operation. If you also plan to use Mac F2C with the THINK C++ compiler, you can run a second test to verify correct operation with the C++ compiler. Start Mac F2C and in the "C Options' dialog, select "C++ code". Do not change any of the other options. Translate "Test.f". Compare it with "Test.c (C++ Output)" to verify that you got the same thing. If so, double click on the THINK project "Test++.π" and follow the same steps outlined in the "Bringing Libraries Up-To-Date" section to bring the test project up-to-date. Run it to verify correct operation. Do not use the "Test++.π" project as the basis for your own C++ based Mac F2C projects. To simplify the testing procedures, the "Test++.π" project maps the ".c" extension to the C++ compiler -- this is not generally desirable and can cause great gnashing of teeth if you forget about this "feature". ***************************************************************************** C. TRANSLATING FORTRAN PROGRAMS ******************************** You can use Mac F2C to translate FORTRAN to C using three methods: (a) Start up Mac F2C and select the "Translate" command in the File menu. (b) Drag-&-drop a bunch of FORTRAN files onto Mac F2C. (c) Use a scripting language (e.g., AppleScript) to send Mac F2C either an 'open' command, an 'f2c' command, or a 'translate' command. For more information on driving Mac F2C from a script see the instructions in the folder "Mac F2C AppleEvents". FORTRAN files must be TEXT files and *must* end in ".f" or ".F" (sorry, but the ending is determined by the unix f2c kernel -- it rejects files handed to it with any other endings). The output file is the same name with a ".c" extension if you selected C code for the output, or the same name with a ".cp" extension if you selected C++ code for the output. The first five items in the Options menu let you control the various translation and code generation options. If you check the "Make these the new defaults" box before clicking the "OK" button, your option selections will be saved in a Preference file and used again the next time you start Mac F2C. If you do not understand what an option means, check the balloon help. The help balloons provide more detailed explanations of what each option means. They also explain why dimmed options are not available and what you can do to make them available. The last item in the Options menu ("Mac F2C Preferences…") lets you control how Mac F2C operates. This dialog lets you control: - How Mac F2C behaves after having been launched with a drag-&-drop. - Whether the "Advanced Options" dialog will have an edit text field that allows you to enter unix option switches directly. - The creator type for all of the output files (determines their icon). - Whether and how Mac F2C interacts with THINK and/or CodeWarrior. If the notify option is checked, Mac F2C will attempt to touch the corresponding THINK or CodeWarrior project file after translating a FORTRAN file into C successfully. If THINK/CodeWarrior is not running or if the file is not part of the current project, Mac F2C will fail silently. If the make option is checked, then Mac F2C will also send a make (e.g., bring up to date) command to THINK/CodeWarrior. If a group of FORTRAN files are translated at once (via a drag-&-drop or via an AppleScript), the make command is not sent until the last file is translated. Again, Mac F2C fails silently if THINK or CodeWarrior can't do it. As in the case of the other option dialogs, check the balloon help if you do not understand what an option means. ***************************************************************************** D. USING C CODE PRODUCED BY MAC F2C ************************************ The C code produced by Mac F2C has the following compile and link requirements: - the header file "f2c.h" - the F2C libraries "libI77a", "libI77b", and "libF77" - the THINK C libraries "ANSI F2C" and "unix F2C" - the Symantec C++ libraries "IOStreams F2C" and "CPlusLib F2C" (C++ only) - 4-byte integers (C only) - 8-byte doubles - native floating-point format - far code - far data - C++ ANSI conformance UNCHECKED (C++ only) In addition, if you compile a stand-alone FORTRAN program (vice only some FORTRAN subroutines) you must include "main.c" in your project (or "main.cp" if you use C++; the two files are identical). This is because the original main routine in the FORTRAN program becomes a function that is called by main.c. In addition, main.c performs a series of initializations (primarily related to error catching) prior to executing the main FORTRAN program. The model project provided ("Mac F2C C Project") is a folder that contains everything you need to compile and run code produced by Mac F2C using the C compiler. This folder has a copy of main.c, f2c.h, and a project file that includes the appropriate libraries and option settings. The C++ model project ("Mac F2C C++ Project") is a folder that contains everything you need to compile and run code produced by Mac F2C using the C++ compiler. This folder has a copy of main.cp, f2c.h, and a project file that includes the appropriate libraries and option settings. If you have THINK C version 7.0 or better, simply create a new project by using the "New" command in the THINK Project Manager's "File" menu and selecting "Mac F2C C Project" or "Mac F2C C++ Project" as the model for the new project. Add your code files as appropriate, bring it up-to-date (you may need to use the "Make" command and the "Use Disk" option the first time), and run. If you have an earlier version of THINK C, first replace the project file provided in "Mac F2C C Project" with one made with your version of THINK (I have included a list of the project contents for your convenience -- see the additional instructions in the file "For THINK v6 and Earlier Users" if you have trouble doing this). Do not include any objects at this time. To start a new project, duplicate the entire "Mac F2C C Project" folder, change the names of files and folders as appropriate, add your code files, and bring everything up-to-date. If you compile a FORTRAN subroutine or function that you want to call from a C program, look at the C code produced by Mac F2C to see the appropriate calling protocol. You may or may not need to include the F2C support libraries (libF77, libI77a, and libI77b). In rare cases, you may also need to copy some of the initialization code from "main.c" to your calling program. As noted above, code produced by Mac F2C *MUST* be compiled with 4-byte integers. This requirement cannot be relaxed. The other requirements (8-byte doubles, native floating-point format, far data, and far code) can sometimes be relaxed: - IF you do not use doubles/reals in any situation where their size relative to integers matters (e.g., if you do not use doubles/reals in equivalence and common statements), then your code probably does not require 8-byte doubles. You need to verify this on a case- by-case basis. This requirement exists because Mac F2C follows FORTRAN sizing rules when compiling FORTRAN code: sizeof(real) == sizeof(integer) and sizeof(double) == 2*sizeof(real). FORTRAN real is compiled as C float and FORTRAN double as C double, so doubles have to be 8-bytes long for equivalence and common statements to be properly aligned. There are a few other cases where the size of double variables matters; see AT&T Computing Science Technical Report No. 149 (included with Mac F2C) for a detailed discussion. - IF you compile your program with the option "Local variables are automatic" and you do not have large static data structures, you *might* not need "Far Data". You need to verify this on a case- by-case basis. Mac F2C creates large static data structures for I/O. If you create local variables in the global area (static vice automatic) or if you have other static data, you will almost certainly require "Far Data". The I/O data structures can be large enough that you may require "Far Data" for that reason alone. - IF your program is not very large and doesn't have a large number of subroutines, you probably will not need "Far Code". You need to verify this on a case-by-case basis. Mac F2C tends to produced redundant copies of utility code (especially code for performing array indexing). It can also produce large numbers of auxiliary functions. The result is that "Far Code" is often required. Compile first with "Far Code", then check the code size and jump table to see if you can relax this requirement. - IF your program will NOT be compiled under Symantec C++ (i.e., you chose K&R C or ANSI C output vice C++ output) and you will not link with code produced by Symantec C++, you do not need native floating- point format. The native floating-point format option is selected only to guarantee compatibility with the Symantec C++ compiler should you chose to use the output of Mac F2C with C++ code. If you change the "8-byte doubles", "native floating-point format", "Far Code", or "Far Data" options, remember to also change them in all the libraries, specifically "libI77a", "libI77b", "libF77", "ANSI F2C", "unix F2C", "IOStreams F2C", and "CPlusLib F2C" (the latter two for C++ only) I urge all users to read the enclosed AT&T Computing Science Technical Report No. 149. Consider it your compiler and language reference manual. You can print the report by downloading it to any PostScript printer. You can use Apple's LaserWriter Utility application to do this or you can use any of the many equivalent utilities.